messaging-api-slack

messaging-api-slack

Messaging API client for Slack

Table of Contents

• Installation
• OAuth Client
  • Usage
  • API Reference
  • Test
• Webhook Client
  • Usage
  • API Reference

Installation

npm i --save messaging-api-slack

or

yarn add messaging-api-slack

OAuth Client

Usage

Get your bot user OAuth access token by setup OAuth & Permissions function to your app or check the Using OAuth 2.0 document.

const { SlackOAuthClient } = require('messaging-api-slack');

// get access token by setup OAuth & Permissions function to your app.
// https://api.slack.com/docs/oauth
const client = SlackOAuthClient.connect(
  'xoxb-000000000000-xxxxxxxxxxxxxxxxxxxxxxxx'
);

API Reference

All methods return a Promise.

Call available methods

callMethod(method, body) - Official docs

Calling any API methods which follow slack calling conventions.

Param	Type	Description
method	String	One of API Methods
body	Object	Body that the method needs.

Example:

client.callMethod('chat.postMessage', { channel: 'C8763', text: 'Hello!' });

Chat API

postMessage(channel, message [, options]) - Official docs

Sends a message to a channel.

Param	Type	Description
channel	String	Channel, private group, or IM channel to send message to. Can be an encoded ID, or a name.
message	String | Object	The message to be sent, can be text message or attachment message.
options	Object	Other optional parameters.

Example:

client.postMessage('C8763', { text: 'Hello!' });
client.postMessage('C8763', { attachments: [someAttachments] });
client.postMessage('C8763', 'Hello!');
client.postMessage('C8763', 'Hello!', { as_user: true });

If you send message with attachments, messaging-api-slack will automatically stringify the attachments field for you.

client.postMessage(
  'C8763',
  {
    text: 'Hello!',
    attachments: [
      {
        text: 'Choose a game to play',
        fallback: 'You are unable to choose a game',
        callback_id: 'wopr_game',
        color: '#3AA3E3',
        attachment_type: 'default',
        actions: [
          {
            name: 'game',
            text: 'Chess',
            type: 'button',
            value: 'chess',
          },
        ],
      },
    ],
  },
  {
    as_user: true,
  }
);

postEphemeral(channel, user, message [, options]) - Official docs

Sends an ephemeral message to a user in a channel.

Param	Type	Description
channel	String	Channel, private group, or IM channel to send message to. Can be an encoded ID, or a name.
user	String	id of the user who will receive the ephemeral message. The user should be in the channel specified by the channel argument.
message	String | Object	The message to be sent, can be text message or attachment message.
options	Object	Other optional parameters.

Example:

client.postEphemeral('C8763', 'U56781234', { text: 'Hello!' });
client.postEphemeral('C8763', 'U56781234', { attachments: [someAttachments] });
client.postEphemeral('C8763', 'U56781234', 'Hello!');
client.postEphemeral('C8763', 'U56781234', 'Hello!', { as_user: true });

Users API

getUserList(cursor?) - Official docs

Lists all users in a Slack team.

Param	Type	Description
cursor	String	Paginate through collections of data by setting the cursor parameter to a next_cursor attribute returned by a previous request's response_metadata.

Example:

client.getUserList(cursor).then(res => {
  console.log(res);
  // {
  //   members: [
  //     { ... },
  //     { ... },
  //   ],
  //   next: 'abcdefg',
  // }
});

getAllUserList() - Official docs

Recursively lists all users in a Slack team using cursor.

Example:

client.getAllUserList().then(res => {
  console.log(res);
  // [
  //   { ... },
  //   { ... },
  // ]
});

getUserInfo(userId) - Official docs

Gets information about an user.

Param	Type	Description
userId	String	User to get info on.

Example:

client.getUserInfo(userId).then(res => {
  console.log(res);
  // {
  //   id: 'U123456',
  //   name: 'bobby',
  //   ...
  // }
});

Channels API

getChannelList() - Official docs

Lists all channels in a Slack team.

Example:

client.getChannelList().then(res => {
  console.log(res);
  // [
  //   { ... },
  //   { ... },
  // ]
});

getChannelInfo(channelId) - Official docs

Gets information about a channel.

Param	Type	Description
channelId	String	Channel to get info on.

Example:

client.getChannelInfo(channelId).then(res => {
  console.log(res);
  // {
  //   id: 'C8763',
  //   name: 'fun',
  //   ...
  // }
});

Conversasions API

getConversationInfo(channelId) - Official docs

Retrieve information about a conversation.

Param	Type	Description
channelId	String	Channel to get info on.

Example:

client.getConversationInfo(channelId).then(res => {
  console.log(res);
  // {
  //   id: 'C8763',
  //   name: 'fun',
  //   ...
  // }
});

getConversationMembers(channelId, options) - Official docs

Retrieve members of a conversation.

Param	Type	Description
channelId	String	Channel to get info on.
options	Object	Optional arguments.

Example:

client.getConversationMembers(channelId, { cursor: 'xxx' });
client.getConversationMembers(channelId).then(res => {
  console.log(res);
  // {
  //   members: ['U061F7AUR', 'U0C0NS9HN'],
  //   next: 'cursor',
  // }
});

getAllConversationMembers(channelId) - Official docs

Recursively retrieve members of a conversation using cursor.

Param	Type	Description
channelId	String	Channel to get info on.

Example:

client.getAllConversationMembers(channelId).then(res => {
  console.log(res);
  // ['U061F7AUR', 'U0C0NS9HN', ...]
});

getConversationList(options) - Official docs

Lists all channels in a Slack team.

Param	Type	Description
options	Object	Optional arguments.

Example:

client.getConversationList({ cursor: 'xxx' });
client.getConversationList().then(res => {
  console.log(res);
  // {
  //   channels: [
  //     {
  //       id: 'C012AB3CD',
  //       name: 'general',
  //       ...
  //     },
  //     {
  //       id: 'C012AB3C5',
  //       name: 'random',
  //       ...
  //     },
  //   ],
  //   next: 'cursor',
  // }
});

getAllConversationList(options) - Official docs

Recursively lists all channels in a Slack team using cursor.

Param	Type	Description
options	Object	Optional arguments.

Example:

client.getAllConversationList().then(res => {
  console.log(res);
  // [
  //   {
  //     id: 'C012AB3CD',
  //     name: 'general',
  //     ...
  //   },
  //   {
  //     id: 'C012AB3C5',
  //     name: 'random',
  //     ...
  //   },
  // ],
});

Test

Point requests to your dummy server

To avoid sending requests to real Slack server, specify origin option when constructing your client:

const { SlackOAuthClient } = require('messaging-api-slack');

const client = SlackOAuthClient.connect({
  accessToken: ACCESS_TOKEN,
  origin: 'https://mydummytestserver.com',
});

Warning: Don't do this on production server.

Webhook Client

Usage

Get your webhook url by adding a Incoming Webhooks integration to your team or setup Incoming Webhooks function to your app.

const { SlackWebhookClient } = require('messaging-api-slack');

// get webhook URL by adding a Incoming Webhook integration to your team.
// https://my.slack.com/services/new/incoming-webhook/
const client = SlackWebhookClient.connect(
  'https://hooks.slack.com/services/XXXXXXXX/YYYYYYYY/zzzzzZZZZZ'
);

API Reference

All methods return a Promise.

Send API - Official docs

sendRawBody(body)

Param	Type	Description
body	Object	Raw data to be sent.

Example:

client.sendRawBody({ text: 'Hello!' });

sendText(text)

Param	Type	Description
text	String	Text of the message to be sent.

Example:

client.sendText('Hello!');

sendAttachments(attachments) - Official docs

Send multiple attachments which let you add more context to a message.

Param	Type	Description
attachments	Array<Object>	Messages are attachments, defined as an array. Each object contains the parameters to customize the appearance of a message attachment.

Example:

client.sendAttachments([
  {
    fallback: 'some text',
    pretext: 'some pretext',
    color: 'good',
    fields: [
      {
        title: 'aaa',
        value: 'bbb',
        short: false,
      },
    ],
  },
  {
    fallback: 'some other text',
    pretext: 'some pther pretext',
    color: '#FF0000',
    fields: [
      {
        title: 'ccc',
        value: 'ddd',
        short: false,
      },
    ],
  },
]);

sendAttachment(attachment) - Official docs

Send only one attachment.

Param	Type	Description
attachments	Object	Message is an attachment. The object contains the parameters to customize the appearance of a message attachment.

Example:

client.sendAttachment({
  fallback: 'some text',
  pretext: 'some pretext',
  color: 'good',
  fields: [
    {
      title: 'aaa',
      value: 'bbb',
      short: false,
    },
  ],
});

Changelog

0.6.13 / 2018-02-12

• [new] Support origin for test:

const { MessengerClient } = require('messaging-api-messenger');

const client = MessengerClient.connect({
  accessToken: ACCESS_TOKEN,
  origin: 'https://mydummytestserver.com',
});